//  Proxy.hpp
//  PureMVC_C++
//
//  PureMVC Port to C++ by Tang Khai Phuong <phuong.tang@puremvc.org>
//  PureMVC - Copyright(c) 2006-2011 Futurescale, Inc., Some rights reserved.
//  Your reuse is governed by the Creative Commons Attribution 3.0 License
//
//  中文注释：
//  Proxy类是IProxy接口的基础实现。
//  它用于管理应用程序数据模型的部分，封装数据访问和操作。
//

#if !defined(__PUREMVC_PATTERNS_PROXY_PROXY_HPP__)
#define __PUREMVC_PATTERNS_PROXY_PROXY_HPP__

// STL include
#include <string>
// PureMVC include
#if !defined(__PUREMVC_HPP__)
#define __PUREMVC_INCLUDE__
#include "../PureMVC.hpp"
#endif /* __PUREMVC_HPP__ */

#include "../../Interfaces/IProxy.hpp"
#include "../Observer/Notifier.hpp"

namespace PureMVC
{
    namespace Patterns
    {
        using Interfaces::IProxy;
        using Interfaces::INotifier;

        /**
         * A base <code>IProxy</code> implementation.
         *
         * <P>
         * In PureMVC, <code>Proxy</code> classes are used to manage parts of the
         * application's data model. </P>
         *
         * <P>
         * A <code>Proxy</code> might simply manage a reference to a local data object,
         * in which case interacting with it might involve setting and
         * getting of its data in synchronous fashion.</P>
         *
         * <P>
         * <code>Proxy</code> classes are also used to encapsulate the application's
         * interaction with remote services to save or retrieve data, in which case,
         * we adopt an asyncronous idiom; setting data (or calling a method) on the
         * <code>Proxy</code> and listening for a <code>Notification</code> to be sent
         * when the <code>Proxy</code> has retrieved the data from the service. </P>
         *
         * @see Core/Model.hpp PureMVC::Core::Model
         *
         * 中文注释：
         * IProxy接口的基础实现。
         *
         * 在PureMVC中，Proxy类用于管理应用程序数据模型的部分。
         *
         * Proxy可能只是管理对本地数据对象的引用，在这种情况下，与它交互可能涉及以同步方式设置和获取其数据。
         *
         * Proxy类还用于封装应用程序与远程服务的交互以保存或检索数据，在这种情况下，我们采用异步方式；
         * 在Proxy上设置数据（或调用方法），并在Proxy从服务检索到数据时监听发送的Notification。
         */
         class PUREMVC_API Proxy
             : public virtual IProxy
             , public virtual INotifier
             , public Notifier
         {
         public:
            /**
             * Copy constructor.
             *
             * 中文注释：
             * 复制构造函数。
             */
            explicit Proxy(Proxy const& arg);

         public:
            /**
             * Constructor.
             *
             * 中文注释：
             * 构造函数。
             *
             * @param proxy_name 代理名称，默认为Proxy::NAME
             * @param data 数据对象指针，默认为NULL
             */
             explicit Proxy(std::string const& proxy_name = Proxy::NAME, void const* data = NULL);

            /**
             * Get the proxy name.
             *
             * 中文注释：
             * 获取代理名称。
             *
             * @return 代理名称
             */
            virtual std::string const& getProxyName(void) const;

            /**
             * Set the data object.
             *
             * 中文注释：
             * 设置数据对象。
             *
             * @param data 要设置的数据对象指针
             */
            virtual void setData(void const* data);

            /**
             * Get the data object.
             *
             * 中文注释：
             * 获取数据对象。
             *
             * @return 数据对象指针
             */
            virtual void const* getData(void) const;

            /**
             * Called by the Model when the Proxy is registered.
             *
             * 中文注释：
             * 当Proxy被注册时由Model调用。
             * 可在此方法中执行初始化操作。
             */
            virtual void onRegister(void);

            /**
             * Called by the Model when the Proxy is removed.
             *
             * 中文注释：
             * 当Proxy被移除时由Model调用。
             * 可在此方法中执行清理操作。
             */
            virtual void onRemove(void);

            /**
             * Assignment operator.
             *
             * 中文注释：
             * 赋值运算符。
             */
            Proxy& operator=(Proxy const& arg);

            /**
             * Virtual destructor.
             *
             * 中文注释：
             * 虚析构函数。
             */
            virtual ~Proxy(void);
        protected:
            // the proxy name
            // 中文注释：代理名称
            std::string _proxy_name;
            // the data object
            // 中文注释：数据对象指针
            void const* _data;
        public:
            static char const* const NAME;
        };
    }
}

#endif /* __PUREMVC_PATTERNS_PROXY_PROXY_HPP__ */
